2. EL 7
  3. man-pages-cs
  4. gethostbyname(3)

Scroll to navigation

GETHOSTBYNAME(3) Linux - příručka programátora GETHOSTBYNAME(3)

JMÉNO

gethostbyname, gethostbyaddr, sethostent, gethostend, endhostent, h_errno, herror, hstrerror, gethostbyaddr_r, gethostbyname2, gethostbyname2_r, gethostbyname_r, gethostent_r, - zjistí záznam z databáze počítačů

SYNTAXE

#include <netdb.h>
extern int h_errno;

struct hostent *gethostbyname(const char *name);

#include <sys/socket.h>      /*AF_INET*/
struct hostent *gethostbyaddr(const char *addr, int len, int type);

void sethostent(int stayopen);

void endhostent(void);

void herror(const char *s);

const char *hstrerror(int err);

/*rozšíření System V/POSIX*/
struct hostent *gethostent(void);

/*rozšíření GNU*/
struct hostent *gethostbyname2(const char *name, int af);


struct hostent *ret, char *buf, size_t buflen,
struct hostent **result, int *h_errnop);

    
struct hostent *ret, char *buf, size_t buflen,
struct hostent **result, int *h_errnop);

    
struct hostent *ret, char *buf, size_t buflen,
struct hostent **result, int *h_errnop);

    
struct hostent *ret, char *buf, size_t buflen,
struct hostent **result, int *h_errnop);
Vyžaduje Feature Test Makro pro glibc (viz feature_test_macros(7)):

gethostbyname2(), gethostent_r(), gethostbyaddr_r(), gethostbyname_r(),
gethostbyname2_r(): _BSD_SOURCE || _SVID_SOURCE

POPIS

Funkce gethostbyname*() a gethostbyaddr*() jsou zastaralé. V programech by měly být nahrazeny funkcemi getaddrinfo(3) a getnameinfo(3).

Funkce gethostbyname() vrací strukturu typu hostent pro zadaný počítač name. V poli name může být buď hostaname nebo IPv4 adresa v klasické tečkové notaci (jako v inet_addr(3)), případně IPv6 adresa v dvojtečkové (případně v tečkové) notaci. (Více informací o formátu IPv6 adres lze nalézt v RFC 1884.) Je-li jméno IPv4 nebo IPv6 adresa není prováděno žádné hledání a gethostbyname() jednoduše zkopíruje name do pole h_name a strukturu struct in_addr do pole h_addr_list[0] ve vracené struktuře hostent. Doména počítače a jí nadřazené jsou prohledávány pouze tehdy, nekončí-li name tečkou. Pokud name nekončí tečkou a proměnná prostředí HOSTALIASES je nastavena, bude prvně prohledáván soubor, na který ukazuje proměnná HOSTALIASES.

Funkce gethostbyaddr() vrací strukturu typu hostent pro počítač, jehož adresa addr (délky len a typu type) byla zadána. Platné typy adres jsou AF_INET a AF_INET6. Parametr adresa hosta je ukazatel do struktury jejíž typ závisí na druhu adresy. Například struct in_addr * (zřejmě získáno skrze volání inet_addr(3)) pro adresy typu AF_INET.

Funkce sethostent() specifikuje, je-li stayopen pravdivé (1), že k dotazování budou použity spojené TCP sokety a spojení zůstane mezi jednotlivými dotazy otevřeno. Jinak budou k dotazování použity UDP datagramy.

Funkce endhostent() ukončí TCP spojení pro dotazy na nameserver.

Funkce herror() vytiskne chybovou zprávu, která přísluší hodnotě proměnné h_errno.

Zastaralá funkce hsterror() vezme číslo chyby (obvykle h_errno) a vrátí odpovídající řetězec.

Funkce gethostbyname() a gethostbyaddr() používají při své činnosti jak nameservery named(8), tak soubor /etc/hosts, ale samozřejmě i NIS nebo YP, to záleží na pořadí definovaném v /etc/host.conf. (Viz resolv+(8)). Standardně je prvně dotazován named(8) a potom soubor /etc/hosts.

Struktura hostent je definována v <netdb.h> následovně:

struct hostent {


    char    *h_name;        /* official name of host */


    char    **h_aliases;        /* alias list */


    int    h_addrtype;        /* host address type */


    int    h_length;        /* length of address */


    char    **h_addr_list;        /* list of addresses */
}
#define h_addr    h_addr_list[0]        /* for backward compatibility */

Prvky struktury hostent jsou:

Oficiální jméno počítače.
Nulou ukončené pole alternativních jmen počítačů.
Typ adres, v současné době vždy AF_INET.
Délka adresy v bajtech.
Nulou ukončené pole síťových adres počítače v síťovém pořadí dat.
První adresa v h_addr_list kvůli zpětné kompatibilitě.

NÁVRATOVÁ HODNOTA

Funkce gethostbyname() a gethostbyaddr() vrací strukturu hostent nebo ukazatel NULL v případě výskytu chyby. Potom je nastavena proměnná h_errno. Pokud je návratová hodnota not-NULL pak zřejmě návratová hodnota odkazuje na statická data. Více informací v poznámkách níže.

ROZEZNÁVANÉ CHYBY

Proměnná h_errno může obsahovat následující hodnoty:

Specifikovaný počítač je neznámý.
Jméno je platné, ale nemá žádnou IP adresu.
Došlo k výskytu neodstranitelné chyby nameserveru.
Došlo k dočasné chybě autoritativního nameserveru. Zkuste později.

SOUBORY

/etc/host.conf
konfigurační soubor resolveru.
/etc/hosts
databáze počítačů.
/etc/nsswitch.conf
konfigurační soubor pro výběr jmenné služby

POZNÁMKY

Funkce gethostbyname() a gethostbyaddr() mohou vracet ukazatele na statická data. Tyto ukazatele mohou být přepsány pozdějším voláním. Zkopírování hodnoty do struct hostent není dostatečné, protože obsahuje ukazatele.

V originálních BSD implementacích měl parametr len funkce gethostbyname() typ int. Standard SUSv2 je chybový a deklaruje parametr len funkce gethostbyaddr() jako typ size_t. (Což je špatně, protože musí být typu int a ne size_t. Norma POSIX.1-2001 mu přiřazuje typ socklen_t

U BSD prototypu funkce gethostbyaddr() je první argument typu const char *.

Norma POSIX.1-2001 označila funkce gethostbyaddr() a gethostbyname() za zastaralé. Viz getaddrinfo(3), getnameinfo(3), gai_sterror(3).

System V/POSIX rozšíření
POSIX vyžaduje, aby volání gethostent() vracelo další záznam z hostitelské databáze. Pokud používáme DNS/BIND tak to nedává moc smysl, nicméně může to být užitečné, pokud hostitelská databáze obsahuje soubory, které mohou být čteny po řádcích. Na mnoha systémech čte tato funkce ze souboru /etc/hosts. Funkce může být dostupná pouze pokud byla knihovna přeložena bez podpory DNS. Glibc verze ignoruje IPv6 záznamy. Tato funkce není reentrantní. Glibc proto přidává reentrantní verzi gethostent_r().

GNU rozšíření
Glibc2 zavádí také funkci gethostbyname2() která pracuje stejně jako funkce gethostbyname(), ale umožňuje specifikaci rodiny do níž musí adresa spadat.

Glibc2 zavádí reentrantní funkce gethostent_r(), gethostbyaddr_r(), gethostbyname_r() a gethostbynbame2_r(). Volající musí poskytnout hostent strukturu ret, která bude v případě úspěchu naplněna, a dočasný pracovní buffer buf o velikosti buflen. Po skončení funkce bude result obsahovat ukazatel na výsledek v případě úspěšného volání. V případě chyby nebo když není nalezen žádný záznam je result NULL. Tato funkce vrací v případě úspěchu 0 a nenulovou hodnotu při v případě chyby. V návaznosti na chyby vracené nereentrantními verzemi je vrácena chyba ERANGE v případě, že je poskytnutý buffer buf příliš malý. Volání by pak mělo být realizováno s větším množstvím paměti. Globální proměnná h_errno není změněna, ale adresa proměnné do které se ukládají čísla chyb je předána h_errnop.

CHYBY

Funkce gethostbyname() nerozeznává části IPv4 adresy, které jsou zadané v tečkové konvenci hexadecimálně.

SPLŇUJE STANDARDY

BSD 4.3

DALŠÍ INFORMACE

getaddrinfo(3), getnameinfo(3), inet(3), inet_ntop(3) inet_pton()3 resolver(3), hosts(5), nsswitch.conf(5), hostname(7), named(8)

TIRÁŽ

Tato stránka je součástí projektu Linux man-pages. Popis projektu a informace o hlášení chyb najdete na http://www.kernel.org/doc/man-pages/.

5. listopadu 2009 BSD